<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="tutorial.css">
<TITLE>
Input and Output
</TITLE>
</HEAD>
<BODY >
<A HREF="tutorial027.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="tutorial023.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="tutorial029.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc58">4.5</A>&nbsp;&nbsp;Input and Output</H2><UL>
<LI><A HREF="tutorial028.html#toc32">Printing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> Terms</A>
<LI><A HREF="tutorial028.html#toc33">Reading ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> Terms</A>
<LI><A HREF="tutorial028.html#toc34">Formatted Output</A>
<LI><A HREF="tutorial028.html#toc35">Streams</A>
</UL>


<A NAME="toc32"></A>
<H3 CLASS="subsection"><A NAME="htoc59">4.5.1</A>&nbsp;&nbsp;Printing ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> Terms</H3>

	<BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
	<DIV CLASS="center">
	<TABLE CELLPADDING=10>
<TR><TD BGCOLOR="#DB9370">
	
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>write(+Stream, ?Term)</B><DD CLASS="dd-description"><BR>
write one term in a default format.
<DT CLASS="dt-description"><B>write_term(+Stream, ?Term, +Options)</B><DD CLASS="dd-description"><BR>
write one term, format options can be selected.
<DT CLASS="dt-description"><B>printf(+Stream, +Format, +ArgList)</B><DD CLASS="dd-description"><BR>
write a string with embedded terms, according to a format string.
<DT CLASS="dt-description"><B>writeq(+Stream, ?Term), write_canonical(+Stream, ?Term)</B><DD CLASS="dd-description"><BR>
write one term so that it can be read back.
<DT CLASS="dt-description"><B>put(+Stream, +Char)</B><DD CLASS="dd-description"><BR>
write one character.
</DL>

	</TD>
</TR></TABLE>
	</DIV>
	<BR>
<BR>
<DIV CLASS="center">Figure 4.3: Builtins for writing</DIV><BR>
<BR>

	<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
The predicates of the write-group are generic in the sense that they
can print any ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> data structure.
The different predicates print slightly different formats.
The <TT>write/1</TT> predicate is intended to be most human-readable, 
while <TT>writeq/1</TT> is designed so that the
printed data can be read back by the predicates of the read-family.
If we print the structured term <CODE>foo(3+4, [1,2], X, 'a b', "string")</CODE>
the results are as follows:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
write:             foo(3 + 4, [1, 2], X, a b, string)
writeq:            foo(3 + 4, [1, 2], _102, 'a b', "string")
</PRE></BLOCKQUOTE>
The write-format is the shortest, but some information is missing,
e.g. that the sequence <CODE>a b</CODE> is an atomic unit and that <CODE>string</CODE>
is a string and not an atom. The writeq-format quotes items properly,
moreover, the variables are printed with unique numbers, so different
variables are printed differently and identical ones identically.<BR>
<BR>
Single characters, encoded in ascii, can be output using <TT>put/1</TT>,
for example: 
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim"> 
[eclipse: 1] put(97).
a
yes.
</PRE></BLOCKQUOTE>
<A NAME="toc33"></A>
<H3 CLASS="subsection"><A NAME="htoc60">4.5.2</A>&nbsp;&nbsp;Reading ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> Terms</H3>

	<BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
	<DIV CLASS="center">
	<TABLE CELLPADDING=10>
<TR><TD BGCOLOR="#DB9370">
	
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>read(+Stream, -Term)</B><DD CLASS="dd-description"><BR>
read one fullstop-terminated ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>term.
<DT CLASS="dt-description"><B>read_term(+Stream, -Term, +Options)</B><DD CLASS="dd-description"><BR>
read one fullstop-terminated ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>term.
<DT CLASS="dt-description"><B>get(+Stream, -Char)</B><DD CLASS="dd-description"><BR>
read one character.
<DT CLASS="dt-description"><B>read_string(+Stream, +Terminator, -Length, -String)</B><DD CLASS="dd-description"><BR>
read a string up to a certain terminator character.
<DT CLASS="dt-description"><B>read_token(+Stream, -Token, -Class)</B><DD CLASS="dd-description"><BR>
read one syntactic token (e.g. a number, an atom, a bracket, etc).
</DL>

	</TD>
</TR></TABLE>
	</DIV>
	<BR>
<BR>
<DIV CLASS="center">Figure 4.4: Builtins for reading</DIV><BR>
<BR>

	<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
If the data to be read is in Prolog syntax, it can be read using
<TT>read(?Term)</TT>.
This predicate reads one fullstop-terminated
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>term from stream Stream.
A fullstop is defined as a dot followed by a layout character like
blank space or newline.
Examples:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
[eclipse 4]: read(X).
 123,a.
X = 123, a
yes.

[eclipse 6]: read(X).
 [3,X,foo(bar),Y].
X = [3, X, foo(bar), Y]
yes.

</PRE></BLOCKQUOTE>
Single characters can be input using <TT>get/1</TT>, which gets their
ascii encoding, for example:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim"> 
[eclipse: 1] get(X).
a
X=97
yes.
</PRE></BLOCKQUOTE>
<A NAME="toc34"></A>
<H3 CLASS="subsection"><A NAME="htoc61">4.5.3</A>&nbsp;&nbsp;Formatted Output</H3>
The printf-predicate is similar to the printf-function in C, with some
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>-specific format extensions.
Here are some examples of printing numbers:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- printf("%d", [123]).
123
yes.
?- printf("%5d,%05d", [123,456]).
  123,00456
yes.
?- printf("%6.2f", [123]).
type error in printf("%6.2f", [123])
?- printf("%6.2f", [123.4]).
123.40
yes.
?- printf("%6.2f", [12.3]).
 12.30
yes.
</PRE></BLOCKQUOTE>
The most important ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>-specific format option is %w, which
allows to print like the predicates of the write-family:
<BLOCKQUOTE CLASS="quote"><PRE CLASS="verbatim">
?- printf("%w", [foo(3+4, [1,2], X, 'a b', "string")]).
foo(3 + 4, [1, 2], X, a b, string)
</PRE></BLOCKQUOTE>
The %w format allows a number of modifiers in order to access all the
existing options for the printing of ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> terms.
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>&#8857;</B><DD CLASS="dd-description"> <FONT COLOR="#9832CC">For details see the
</FONT><A HREF="../bips/kernel/ioterm/write_term-2.html"><FONT COLOR="#9832CC"><B>write_term/2</B></FONT></A><A NAME="@default88"></A><FONT COLOR="#9832CC">
and
</FONT><A HREF="../bips/kernel/ioterm/printf-2.html"><FONT COLOR="#9832CC"><B>printf/2</B></FONT></A><A NAME="@default89"></A><FONT COLOR="#9832CC">
predicates.</FONT>
</DL>

<A NAME="toc35"></A>
<H3 CLASS="subsection"><A NAME="htoc62">4.5.4</A>&nbsp;&nbsp;Streams</H3>
ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> I/O is done from and to named channels called streams. 
The following streams are always opened when ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is running:
<B>input</B> (used by the input predicates that do not have
an explicit stream argument, e.g. <A HREF="../bips/kernel/ioterm/read-1.html"><B>read/1</B></A><A NAME="@default90"></A>
<A NAME="@default91"></A><A NAME="@default92"></A>),
<B>output</B> (used by the output predicates that do not have
an explicit stream argument, e.g. <A HREF="../bips/kernel/ioterm/write-1.html"><B>write/1</B></A><A NAME="@default93"></A>
<A NAME="@default94"></A><A NAME="@default95"></A>),
<B>error</B> (output for error messages and all messages about exceptional states
<A NAME="@default96"></A>),
<B>warning_output</B> (used by the system to output warning messages
<A NAME="@default97"></A>),
<B>log_output</B> (used by the system to output log messages, e.g. messages about garbage
collection activity
<A NAME="@default98"></A>),
<B>null</B> (<A NAME="@default99"></A>
a dummy stream, output to it is discarded, on input it always
gives end of file).<BR>
<BR>
Data can be read from a specific stream using
<A HREF="../bips/kernel/ioterm/read-2.html"><B>read(+Stream,
?Term)</B></A><A NAME="@default100"></A>,
and written to a specific stream using
<A HREF="../bips/kernel/ioterm/write-2.html"><B>write(+Stream,
?Term)</B></A><A NAME="@default101"></A>.
If no particular stream is specified, input predicates read from <B>input</B>
and output predicates write to <B>output</B>.<BR>
<BR>
New streams may be opened onto various I/O devices, see figure <A HREF="#ioopen">4.5</A>.
<BLOCKQUOTE CLASS="figure"><DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV>
<DIV CLASS="center">
<TABLE BORDER=1 CELLSPACING=0 CELLPADDING=1>
<TR><TD ALIGN=center NOWRAP>I/O device</TD>
<TD ALIGN=left NOWRAP>How to open</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>tty</TD>
<TD ALIGN=left NOWRAP>implicit (stdin,stdout,stderr) or
 <A HREF="../bips/kernel/iostream/open-3.html"><B>open/3</B></A><A NAME="@default102"></A> of a device file</TD>
</TR>
<TR><TD ALIGN=center NOWRAP>file</TD>
<TD ALIGN=left NOWRAP><A HREF="../bips/kernel/iostream/open-3.html"><B>open(FileName, Mode, Stream)</B></A><A NAME="@default103"></A></TD>
</TR>
<TR><TD ALIGN=center NOWRAP>string</TD>
<TD ALIGN=left NOWRAP><A HREF="../bips/kernel/iostream/open-3.html"><B>open(string(String), Mode, Stream)</B></A><A NAME="@default104"></A></TD>
</TR>
<TR><TD ALIGN=center NOWRAP>queue</TD>
<TD ALIGN=left NOWRAP><A HREF="../bips/kernel/iostream/open-3.html"><B>open(queue(String), Mode, Stream)</B></A><A NAME="@default105"></A></TD>
</TR>
<TR><TD ALIGN=center NOWRAP>pipe</TD>
<TD ALIGN=left NOWRAP><A HREF="../bips/kernel/opsys/exec-2.html"><B>exec/2</B></A><A NAME="@default106"></A>,
 <A HREF="../bips/kernel/opsys/exec-3.html"><B>exec/3</B></A><A NAME="@default107"></A> and
 <A HREF="../bips/kernel/opsys/exec_group-3.html"><B>exec_group/3</B></A><A NAME="@default108"></A></TD>
</TR>
<TR><TD ALIGN=center NOWRAP>socket</TD>
<TD ALIGN=left NOWRAP><A HREF="../bips/kernel/iostream/socket-3.html"><B>socket/3</B></A><A NAME="@default109"></A> and
 <A HREF="../bips/kernel/iostream/accept-3.html"><B>accept/3</B></A><A NAME="@default110"></A></TD>
</TR>
<TR><TD ALIGN=center NOWRAP>null</TD>
<TD ALIGN=left NOWRAP>implicit (null stream)</TD>
</TR></TABLE>
</DIV>
<BR>
<BR>
<DIV CLASS="center">Figure 4.5: How to open streams onto the different I/O devices</DIV><BR>
<BR>

<A NAME="ioopen"></A>
<DIV CLASS="center"><HR WIDTH="80%" SIZE=2></DIV></BLOCKQUOTE>
All types of streams are closed using
<A HREF="../bips/kernel/iostream/close-1.html"><B>close(+Stream)</B></A><A NAME="@default111"></A>.

<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>&#8857;</B><DD CLASS="dd-description"> <FONT COLOR="#9832CC">See the complete description of the
stream-related built-in predicates in the Reference Manual</FONT>
</DL>

For network communication over sockets, there is a full set of predicates
modelled after the BSD socket interface:
<B>socket/3</B><A NAME="@default112"></A>,
<B>accept/3</B><A NAME="@default113"></A>,
<B>bind/2</B><A NAME="@default114"></A>,
<B>listen/2</B><A NAME="@default115"></A>,
<B>select/3</B><A NAME="@default116"></A>.
See the reference manual for details.<BR>
<BR>
Output in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> is usually buffered, i.e. printed text goes into
a buffer and may not immediately appear on the screen, in a file, or
be sent via a network connection. Use
<A HREF="../bips/kernel/iostream/flush-1.html"><B>flush(+Stream)</B></A><A NAME="@default117"></A>
to empty the buffer and write all data to the underlying device.<BR>
<BR>
<HR>
<A HREF="tutorial027.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="tutorial023.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="tutorial029.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
